<?xml version="1.0" encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook">
  <section>
    <sectioninfo>
      <title>DBGP - A common debugger protocol for languages and debugger UI communication</title>
      <author>Shane Caraveo, ActiveState &lt;shanec@ActiveState.com&gt;  Derick Rethans &lt;derick@derickrethans.nl&gt;</author>
    </sectioninfo>
    <section>
      <title>DBGP - A common debugger protocol for languages and debugger UI communication</title>
      <para>Contents</para>
      <section>
        <title>
          <link linked="id11">1. Description</link>
        </title>
        <para>This document describes a simple protocol for use with language tools
and engines for the purpose of debugging applications.  It does not
describe user interfaces or interactions with the debugger.  The
protocol provides a means of communication between a debugger
engine (scripting engine, vm, etc.) and a debugger IDE (IDE, etc.).
Any references to the debugger IDE UI are recommendations only, and are
provided for additional explanation or as reasoning for specific
design decisions.</para>
      </section>
      <section>
        <title>
          <link linked="id12">1.1 Issues</link>
        </title>
        <para>1. The handling of proxy errors needs to be clarified.  Without both
IDE and debugger engine supporting commands to be received at
arbitrary times, the proxy may have problems sending error or status
information to either one.  See section 5.3.2.  We should think a bit
more about what a proxy might need to do.</para>
      </section>
      <section>
        <title>
          <link linked="id13">2. Requirements</link>
        </title>
      </section>
      <section>
        <title>
          <link linked="id14">3. Terminology</link>
        </title>
      </section>
      <section>
        <title>
          <link linked="id15">4. Security</link>
        </title>
        <para>It is expected that implementations will provide security, such as ip
filtering, ssh tunneling, etc.  This protocol itself does not provide
a means of securing the debugging session.</para>
      </section>
      <section>
        <title>
          <link linked="id16">5. Initiating a debugging session</link>
        </title>
        <para>The debugger engine initiates a debugging session.  The debugger engine
will make a connection to a listening IDE, then wait for the IDE to
initiate commands.  The debugger engine does not step into the first line of
execution until the IDE issues one of the continuation commands.
The first thing that should happen in a debug session is that the IDE
negotiates features using the feature_get and feature_set commands, and sets
any additional data, such as breakpoints.  Debugger engine implementations
should store and data it receives if it is unable to process them prior to
compiling and/or executing code.  Commands such as stack_get should not be
expected to work during this phase, otherwise known as the 'starting' state (see
section 7.1 for status levels).</para>
        <para>Likewise, at the end of a debug session, there is a 'stopping' state.  This state
is entered after all execution is complete.  For most debugger engine implementations,
only a 'stop' command can be accepted at this point, however some implementations
may provide additional commands for retrieving various data from the engine for
post debug session processing.</para>
      </section>
    </section>
  </section>
</article>
